docs: add drive comment location guidance by wittam-01 · Pull Request #1258 · larksuite/cli

wittam-01 · 2026-06-04T04:05:07Z

Summary

Adds guidance for locating document comments using need_relation=true, relation block IDs, and embedded resource parent metadata.

Changes

Link the lark-drive skill to a new comment location reference for review/comment mapping workflows.
Document relation parsing, positionInfo.blockID matching, parent_type / parent_token handling, and accuracy levels.
Add follow-up guidance for Sheet, Base/Bitable, and Whiteboard internal comments.

Test Plan

git diff --check HEAD~1..HEAD
Unit tests pass — not run; documentation-only Skill change.
Manual local verification confirms the lark-cli <domain> <command> flow works as expected — not run; guidance-only Skill change.

Related Issues

None

Summary by CodeRabbit

Documentation
- Added guidance requiring use of the new "快速决策" rule and enabling need_relation=true when locating comments to document content.
- New section describing how comment relation data maps to document positions, including using relation to resolve block IDs.
- Documented workflows for locating comments inside embedded content (parent_type/parent_token) and fallback strategies.

coderabbitai · 2026-06-04T04:05:20Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3e4fff9f-93a6-4d0c-85be-ae40667f1d6c

📥 Commits

Reviewing files that changed from the base of the PR and between ef3e9c0 and dbe35be.

📒 Files selected for processing (2)

skills/lark-drive/SKILL.md
skills/lark-drive/references/lark-drive-comment-location.md

✅ Files skipped from review due to trivial changes (2)

skills/lark-drive/SKILL.md
skills/lark-drive/references/lark-drive-comment-location.md

📝 Walkthrough

Walkthrough

SKILL.md adds routing rules requiring need_relation=true for comment-to-body positioning and points to a new reference. The reference defines field semantics (relation, parent_type, parent_token), shows how to parse relation.relation to extract block IDs via docs +fetch --detail with-ids, and prescribes a priority flow for embedded resources and quote fallbacks.

Changes

Lark Drive comment-location positioning

Layer / File(s)	Summary
SKILL.md routing to comment-location reference `skills/lark-drive/SKILL.md`	Quick-decision rule and comment-positioning-fields guidance direct users to the comment-location reference and require `need_relation=true` in comment queries.
Comment-location reference: objectives, usage, and field semantics `skills/lark-drive/references/lark-drive-comment-location.md`	Documents applicability (docx support), how to set `need_relation` for paged/batched queries, how to fetch docs with `--detail with-ids`, and defines `relation`/`parent_type`/`parent_token` with a three-tier accuracy classification.
Comment-location reference: positioning examples and end-to-end flow `skills/lark-drive/references/lark-drive-comment-location.md`	Examples show parsing `relation.relation` JSON to extract `positionInfo.blockID`, matching blocks in fetched docs, and the ordered workflow: relation → parent-embedding → quote fallback.
Comment-location reference: embedded resources guidance and usage principles `skills/lark-drive/references/lark-drive-comment-location.md`	Per-embed guidance: Sheets (cell coord + lark-sheets verification), Bitable/Base (`parent_token` parsing + lark-base drill-down, pagination handling), Whiteboard (raw-node reads + text-match confirmation). Emphasizes preferring block-id over quote.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

larksuite/cli#981: Both PRs update skills/lark-drive comment/positioning guidance—this PR adds need_relation=true and field-priority mapping; the related PR updates comment placement and local comment guidance.

Suggested labels

domain/ccm

Suggested reviewers

fangshuyu-768
SunPeiYang996

Poem

🐰 A rabbit hops through comment trails,
Parsing relations and parent tales,
From docx blocks to sheets and boards,
need_relation=true opens location doors,
I nibble paths and leave bright trails ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main change—adding documentation guidance for locating drive comments—which aligns with the changeset contents.
Description check	✅ Passed	The description covers all required template sections: Summary, Changes, Test Plan, and Related Issues. It provides clear context about the guidance additions and testing approach.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/drive-comment-location-skill

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

codecov · 2026-06-04T04:09:33Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 70.33%. Comparing base (b216363) to head (dbe35be).
⚠️ Report is 32 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1258      +/-   ##
==========================================
+ Coverage   69.19%   70.33%   +1.13%     
==========================================
  Files         634      672      +38     
  Lines       59482    65322    +5840     
==========================================
+ Hits        41161    45941    +4780     
- Misses      15007    15728     +721     
- Partials     3314     3653     +339

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-06-04T04:10:00Z

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@dbe35be23206bc3ad8f741f74d76c6a3a3e49ace

🧩 Skill update

npx skills add larksuite/cli#docs/drive-comment-location-skill -y -g

Change-Id: I7cfdfd5a456658cca89fc974ef7a85dc20c2c395

…#1258 Replaces the client-side quote/text-matching orphan detection with the server-supplied anchor identifiers from `need_relation=true`, following the field design documented in larksuite#1258. Behavior: - list comments with `need_relation=true` to obtain `relation.relation` (containing `positionInfo.blockID`) and `content_deleted` - fetch docs XML with `export_block_id=true`; build a block-id index for stable anchor ordering (replaces the prior text-position projection that broke on multi-occurrence and tag-broken anchors) - use `content_deleted` as the orphan signal (resolves the prior "short anchor multi-occurrence" false-positive limitation) - use `parent_type` / `parent_token` to place embedded-resource comments (Sheet / Base / Whiteboard); intentionally downgrade these to `parent_resource_exact` rather than claiming exact internal ordering, since docs XML only identifies the embedding block Output contract additions: - `anchor_block_id`: per-comment anchor (from positionInfo.blockID) - `location_accuracy`: relation_exact | parent_resource_exact | weak_inferred | content_deleted | whole_document - `content_deleted`: server-side orphan signal Tests: - unit: relation parsing, malformed-JSON fallback, content-deleted orphan classification, relation-exact / parent-resource-exact anchoring, embedded-relation downgrade, sorted output, dry-run request shape, httpmock E2E - dry-run E2E (`tests/cli_e2e/drive/drive_list_comments_dryrun_test.go`): asserts `need_relation=true`, `need_reaction=true`, `is_solved=false`, and fetch body `format=xml` with `export_block_id=true` - opt-in live E2E (`tests/cli_e2e/drive/drive_list_comments_workflow_test.go`): gated by `LARK_DRIVE_LIST_COMMENTS_E2E=1`; user identity; creates a docx, adds a block comment, lists, asserts relation metadata, cleans up - coverage doc updated to 11 / 32 = 34.4% Live validation against a real docx: composition now matches the Lark UI side panel for 21 of 22 originally observed comments (the prior algorithm had a 2-item swap error from text-matching false positives); `[Sticky note]` and embedded `<callout>` comments now land at their correct positions.

github-actions Bot added the size/M Single-domain feat or fix with limited business impact label Jun 4, 2026

docs: add drive comment location guidance

dbe35be

Change-Id: I7cfdfd5a456658cca89fc974ef7a85dc20c2c395

wittam-01 force-pushed the docs/drive-comment-location-skill branch from ef3e9c0 to dbe35be Compare June 5, 2026 08:29

kyalpha313 mentioned this pull request Jun 8, 2026

feat(drive): add +list-comments shortcut with anchor-aware filtering #1114

Draft

8 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add drive comment location guidance#1258

docs: add drive comment location guidance#1258
wittam-01 wants to merge 1 commit into
mainfrom
docs/drive-comment-location-skill

wittam-01 commented Jun 4, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 4, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

codecov Bot commented Jun 4, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 4, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

wittam-01 commented Jun 4, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Test Plan

Related Issues

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

codecov Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 PR Preview Install Guide

🧰 CLI update

🧩 Skill update

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

wittam-01 commented Jun 4, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 4, 2026 •

edited

Loading

codecov Bot commented Jun 4, 2026 •

edited

Loading

github-actions Bot commented Jun 4, 2026 •

edited

Loading